Web SDK

Bauen Sie AR Clip VPS in Ihre eigene Webseite ein. Das Web SDK bestimmt direkt im Browser, wo der Besucher auf Ihren VPS-Karten steht, ganz ohne App-Installation.

Bevor Sie beginnen

Ein API-Schlüssel. Schreiben Sie uns über den Support, um einen zu erhalten.
Standort-IDs Ihrer Karten. Jede Karte hat eine, siehe Einführung.
Eine Seite über HTTPS. Browser geben Kamera und Bewegungssensoren nur für sichere Seiten frei. localhost gilt ebenfalls als sicher.

Installieren

npm install @web-ar-studio/webar-engine-sdk

Das Paket liegt auf npm und bringt seine TypeScript-Typen mit.

VPS starten

VPS läuft innerhalb einer Sitzung mit Welt-Tracking. Geben Sie init() das Feld vps mit und listen Sie darin Ihre Standort-IDs auf. Das SDK zeichnet selbst nichts. Rendern Sie die Szene mit einer Engine Ihrer Wahl: three.js, Babylon.js, PlayCanvas oder reinem WebGL.

import * as THREE from "three";
import WAS, {
  PROJECT_MODE_SLAM,
  TRIGGER_MODE_SLAM,
  CAMERA_MODE_ENVIRONMENT,
  PROVIDER_8THWALL,
  EVENT_FRAME,
  EVENT_VPS_READY,
  EVENT_VPS_LOCALIZED,
  EVENT_VPS_NOT_LOCALIZED,
  EVENT_VPS_ERROR,
} from "@web-ar-studio/webar-engine-sdk";

const was = new WAS();

const { canvas, context } = await was.init({
  apiKey: "your-api-key",
  mode: PROJECT_MODE_SLAM,
  cameraMode: CAMERA_MODE_ENVIRONMENT,
  container: document.querySelector("#ar"),
  triggers: [{ id: 1, mode: TRIGGER_MODE_SLAM, source: null }],
  vps: { locationIds: ["your-location-id"] },
});

const renderer = new THREE.WebGLRenderer({ canvas, context });

was.on(EVENT_VPS_READY, () => console.log("VPS started"));
was.on(EVENT_VPS_LOCALIZED, ({ locationId, offset }) => {
  console.log("Found the place on map", locationId, offset);
});
was.on(EVENT_VPS_NOT_LOCALIZED, ({ status, statusDescription }) => {
  console.log("Not found yet:", status, statusDescription);
});
was.on(EVENT_VPS_ERROR, (message) => console.warn("VPS error:", message));

// Tracking und VPS starten mit dem Frame-Callback. Registrieren Sie ihn bei einem Tippen:
// WebXR und die Bewegungssensoren auf dem iPhone brauchen eine Geste des Nutzers.
startButton.onclick = () =>
  was.on(EVENT_FRAME, () => renderer.render(scene, camera));

Lassen Sie locationIds weg, lokalisiert VPS global, ohne eine bestimmte Karte. Das dauert länger, erhöhen Sie deshalb requestTimeoutMs.

vps an init() übergeben

In Chrome auf Android wird der Kamerazugriff für VPS nur beim Start der Sitzung gewährt. Starten Sie ohne vps, lässt sich VPS in dieser Sitzung nicht mehr einschalten: setupVPS() wirft VpsError.

Wo es funktioniert

Das SDK wählt auf dem Gerät eine Tracking-Engine (provider). Mit der Voreinstellung "auto" probiert es zuerst webxr, dann 8thwall.

Engine	Wo	VPS
`webxr`	Chrome auf Android	Ja. Das SDK setzt die Szene selbst auf die Karte.
`8thwall`	Browser ohne WebXR, zum Beispiel Safari auf dem iPhone	Ja. `offset` wenden Sie selbst an.
`arclip-webar`	Nur, wenn Sie es ausdrücklich wählen	Nein

Inhalte auf der Karte

Platzieren Sie Ihre Inhalte in den Koordinaten Ihrer VPS-Karte. Sobald VPS den Ort findet, liefert EVENT_VPS_LOCALIZED den Wert offset: die Verschiebung von der Tracking-Welt auf die Karte.

Auf webxr hat das SDK offset bereits angewendet und blendet die Korrektur weich ein. Die Inhalte der Karte stehen also an ihrem Platz.
Auf 8thwall meldet das SDK offset nur. Legen Sie die Inhalte der Karte in eine Gruppe und geben Sie der Gruppe bei jeder Lokalisierung die Umkehrung von offset:

const mapRoot = new THREE.Group(); // alles, was in Kartenkoordinaten platziert ist
scene.add(mapRoot);

was.on(EVENT_VPS_LOCALIZED, ({ offset }) => {
  if (was.getActiveProviderId() !== PROVIDER_8THWALL) return; // webxr wendet es selbst an
  const { position: p, orientation: q } = offset;
  new THREE.Matrix4()
    .compose(
      new THREE.Vector3(p.x, p.y, p.z),
      new THREE.Quaternion(q.x, q.y, q.z, q.w),
      new THREE.Vector3(1, 1, 1),
    )
    .invert()
    .decompose(mapRoot.position, mapRoot.quaternion, mapRoot.scale);
});

Das SDK übernimmt ein Ergebnis nur, wenn die Übereinstimmung sicher genug ist und der Sprung seit dem letzten Ergebnis zu Fuß machbar wäre. Alles andere kommt als EVENT_VPS_NOT_LOCALIZED an. So springen Inhalte nicht an Orten, die sich ähneln, etwa in langen Fluren.

Ereignisse

Ereignis	Was Sie erhalten
`EVENT_VPS_READY`	Nichts. VPS ist gestartet.
`EVENT_VPS_LOCALIZED`	`locationId`, `offset` (`position`, `orientation`), `trackingPosition`, `trackingRotation`, `vpsPosition`, `vpsRotation`, `timestamp`
`EVENT_VPS_NOT_LOCALIZED`	`status`, `statusDescription`, `failCount`
`EVENT_VPS_ERROR`	Eine Fehlermeldung als String

VPS steuern

Methode	Was sie tut
`startVPS()`, `stopVPS()`	Setzt die Lokalisierung fort oder pausiert sie
`isVPSActive()`	Sagt, ob VPS läuft
`setVPSLocationIds(ids)`	Wechselt zu anderen Karten; eine leere Liste lokalisiert global
`setupVPS(config)`	Ändert die VPS-Einstellungen während einer Sitzung
`updateVPSSession()`	Startet eine neue VPS-Sitzung, sodass frühere Ergebnisse neue nicht mehr beeinflussen
`resetTracking()`	Verwirft die VPS-Korrektur und beginnt neu, zum Beispiel nach einem falschen Ergebnis

Einstellungen

Alle Felder von vps sind optional. apiKey übernimmt das SDK aus init(), Sie müssen ihn nicht wiederholen.

Feld	Standard	Was es tut
`locationIds`	keine	Karten, mit denen das Kamerabild verglichen wird. Ohne sie lokalisiert VPS global.
`captureInterval`	`2500`	Abstand zwischen Lokalisierungsanfragen, in ms
`requestTimeoutMs`	`20000`	Wie lange auf eine Antwort gewartet wird, in ms
`maxFailsCount`	`5`	Fehlversuche in Folge, nach denen das SDK eine neue VPS-Sitzung beginnt
`imageFormat`	`"jpeg"`	`"jpeg"` oder `"webp"`. Nehmen Sie WebP nur mit einem Server, der es lesen kann. Kann der Browser kein WebP kodieren, sendet das SDK JPEG.
`jpegQuality`	`1`	Bildqualität, von 0 bis 1
`targetWidth`, `targetHeight`	`540`, `960`	Größe des Bildes, das an den Server geht
`minInlierRatio`, `minNumInliers`	`0.6`, `600`	Wie sicher eine Übereinstimmung sein muss, damit sie zählt
`maxJumpBaseMeters`, `maxJumpSpeedMps`	`3`, `2`	Wie weit sich ein neues Ergebnis vom letzten entfernen darf: `maxJumpBaseMeters` plus `maxJumpSpeedMps` für jede Sekunde seit dem letzten Ergebnis
`serverUrl`	AR Clip VPS	Ein anderer VPS-Server
`sendApiKeyHeader`	`true`	Sendet den Schlüssel im Header `x-vps-apikey`. Schalten Sie das nur für Ihren eigenen Server ab, der diesen Header nicht annimmt.

Fehler

Kann VPS in dieser Sitzung nicht laufen, schlägt init() oder eine VPS-Methode mit einem Fehler namens VpsError fehl (Konstante VPS_ERROR). Fehler nach dem Start, etwa eine gescheiterte Anfrage, kommen über EVENT_VPS_ERROR.

Mehr

Die README des Pakets beschreibt die übrigen Tracking-Modi, Anker und die vollständige Einrichtung mit three.js.
Um VPS ohne Code einzurichten, nutzen Sie VPS-Szenen in AR Clip Studio.

Weiter: Unterstützte Geräte – Smartphones, Browser und Headsets.

Bevor Sie beginnen​

Installieren​

VPS starten​

Wo es funktioniert​

Inhalte auf der Karte​

Ereignisse​

VPS steuern​

Einstellungen​

Fehler​

Mehr​